package org.marketlive.entity.attributes;

/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/

/**
 * Base interface that all home interfaces should extend.
 */
public interface IEntityHome {

    /**
     * Creates a new instance of the object and inserts it into the database.
     *
     * @return      an object instance whose key is the next available key ID,
     *              or null if the object could not be created
     * @throws      Exception if an error occurs
     */
    Object create() throws Exception;

    /**
     * Deletes the object with the given key from the persistent store.
     *
     * @param       objectKey the key of the object to delete
     * @return      true if the object is deleted, false otherwise
     * @throws      Exception if an error occurs
     */
    boolean delete(Object objectKey) throws Exception;

     /**
     * Marks as deleted the object with the given key.
     *
     * @param       objectKey the key of the object to be flagged as deleted
     * @return      true if the object is marked deleted, false otherwise
     * @throws      Exception if an error occurs
     * @deprecated as of MarketLive 5.5 without replacement. Will be removed in the next major release since 
     * soft delete will not be supported.
     */
    boolean flagDelete(Object objectKey) throws Exception;

    /**
     * Returns the object with the given key.
     *
     * @param       objectKey the key of the object to find
     * @return      the found object
     * @throws      Exception if an error occurs
     */
    Object findByKey(Object objectKey) throws Exception;

    /**
     * Updates the given object in the persistent store.
     *
     * @param       object the object to be updated. Must already be present in the persistent store.
     * @return      true if the update succeeds, false otherwise
     * @throws      Exception if an error occurs
     */
    boolean update(Object object) throws Exception;

}
